From 2bd38dc7f5fe6aa4a555764343469cd22e219575 Mon Sep 17 00:00:00 2001 From: Pavel Holejsovsky Date: Sat, 15 Jan 2011 14:50:24 +0100 Subject: [PATCH] Move GtkFixed docs inline Also remove incorrect documentation of opaque GtkFixed class struct. --- docs/reference/gtk/tmpl/.gitignore | 1 + docs/reference/gtk/tmpl/gtkfixed.sgml | 133 -------------------------- gtk/gtkfixed.c | 74 ++++++++++++++ 3 files changed, 75 insertions(+), 133 deletions(-) delete mode 100644 docs/reference/gtk/tmpl/gtkfixed.sgml diff --git a/docs/reference/gtk/tmpl/.gitignore b/docs/reference/gtk/tmpl/.gitignore index dc9c131e6f..d8417c904c 100644 --- a/docs/reference/gtk/tmpl/.gitignore +++ b/docs/reference/gtk/tmpl/.gitignore @@ -26,6 +26,7 @@ gtkenum.sgml gtkeventbox.sgml gtkexpander.sgml gtkfeatures.sgml +gtkfixed.sgml gtkhbox.sgml gtkiconview.sgml gtkimcontextsimple.sgml diff --git a/docs/reference/gtk/tmpl/gtkfixed.sgml b/docs/reference/gtk/tmpl/gtkfixed.sgml deleted file mode 100644 index b2366aa2fd..0000000000 --- a/docs/reference/gtk/tmpl/gtkfixed.sgml +++ /dev/null @@ -1,133 +0,0 @@ - -GtkFixed - - -A container which allows you to position widgets at fixed coordinates - - - -The #GtkFixed widget is a container which can place child widgets at fixed -positions and with fixed sizes, given in pixels. #GtkFixed performs no -automatic layout management. - - - -For most applications, you should not use this container! It keeps -you from having to learn about the other GTK+ containers, but it -results in broken applications. -With #GtkFixed, the following things will result in truncated text, -overlapping widgets, and other display bugs: - - -Themes, which may change widget sizes. - - - -Fonts other than the one you used to write the app will of -course change the size of widgets containing text; keep in mind that -users may use a larger font because of difficulty reading the default, -or they may be using Windows or the framebuffer port of GTK+, where -different fonts are available. - - - - -Translation of text into other languages changes its size. Also, -display of non-English text will use a different font in many cases. - - - - - - -In addition, the fixed widget can't properly be mirrored in -right-to-left languages such as Hebrew and Arabic. i.e. normally GTK+ -will flip the interface to put labels to the right of the thing they -label, but it can't do that with #GtkFixed. So your application will -not be usable in right-to-left languages. - - - -Finally, fixed positioning makes it kind of annoying to add/remove GUI -elements, since you have to reposition all the other elements. This is -a long-term maintenance problem for your application. - - - -If you know none of these things are an issue for your application, -and prefer the simplicity of #GtkFixed, by all means use the -widget. But you should be aware of the tradeoffs. - - - - - - - - - - - - - - - -The #GtkFixed-struct struct contains the following fields. -(These fields should be considered read-only. They should never be set by -an application.) - - - - - - -#GList *children; -a list of #GtkFixedChild elements, containing the child widgets and -their positions. - - - - - - - - - - - - - - - - - - -Creates a new #GtkFixed. - - -@void: -@Returns: a new #GtkFixed. - - - - -Adds a widget to a #GtkFixed container at the given position. - - -@fixed: a #GtkFixed. -@widget: the widget to add. -@x: the horizontal position to place the widget at. -@y: the vertical position to place the widget at. - - - - -Moves a child of a #GtkFixed container to the given position. - - -@fixed: a #GtkFixed. -@widget: the child widget. -@x: the horizontal position to move the widget to. -@y: the vertical position to move the widget to. - - diff --git a/gtk/gtkfixed.c b/gtk/gtkfixed.c index d75f599b12..e61f03a625 100644 --- a/gtk/gtkfixed.c +++ b/gtk/gtkfixed.c @@ -24,6 +24,55 @@ * GTK+ at ftp://ftp.gtk.org/pub/gtk/. */ +/** + * SECTION:gtkfixed + * @Short_description: A container which allows you to position + * widgets at fixed coordinates + * @Title: GtkFixed + * + * The #GtkFixed widget is a container which can place child widgets + * at fixed positions and with fixed sizes, given in pixels. #GtkFixed + * performs no automatic layout management. + * + * For most applications, you should not use this container! It keeps + * you from having to learn about the other GTK+ containers, but it + * results in broken applications. With #GtkFixed, the following + * things will result in truncated text, overlapping widgets, and + * other display bugs: + * + * + * Themes, which may change widget sizes. + * + * + * Fonts other than the one you used to write the app will of course + * change the size of widgets containing text; keep in mind that + * users may use a larger font because of difficulty reading the + * default, or they may be using Windows or the framebuffer port of + * GTK+, where different fonts are available. + * + * + * Translation of text into other languages changes its size. Also, + * display of non-English text will use a different font in many + * cases. + * + * + * + * In addition, the fixed widget can't properly be mirrored in + * right-to-left languages such as Hebrew and Arabic. i.e. normally + * GTK+ will flip the interface to put labels to the right of the + * thing they label, but it can't do that with #GtkFixed. So your + * application will not be usable in right-to-left languages. + * + * Finally, fixed positioning makes it kind of annoying to add/remove + * GUI elements, since you have to reposition all the other + * elements. This is a long-term maintenance problem for your + * application. + * + * If you know none of these things are an issue for your application, + * and prefer the simplicity of #GtkFixed, by all means use the + * widget. But you should be aware of the tradeoffs. + */ + #include "config.h" #include "gtkfixed.h" @@ -132,6 +181,13 @@ gtk_fixed_init (GtkFixed *fixed) fixed->priv->children = NULL; } +/** + * gtk_fixed_new: + * + * Creates a new #GtkFixed. + * + * Returns: a new #GtkFixed. + */ GtkWidget* gtk_fixed_new (void) { @@ -158,6 +214,15 @@ get_child (GtkFixed *fixed, return NULL; } +/** + * gtk_fixed_put: + * @fixed: a #GtkFixed. + * @widget: the widget to add. + * @x: the horizontal position to place the widget at. + * @y: the vertical position to place the widget at. + * + * Adds a widget to a #GtkFixed container at the given position. + */ void gtk_fixed_put (GtkFixed *fixed, GtkWidget *widget, @@ -210,6 +275,15 @@ gtk_fixed_move_internal (GtkFixed *fixed, gtk_widget_queue_resize (GTK_WIDGET (fixed)); } +/** + * gtk_fixed_move: + * @fixed: a #GtkFixed. + * @widget: the child widget. + * @x: the horizontal position to move the widget to. + * @y: the vertical position to move the widget to. + * + * Moves a child of a #GtkFixed container to the given position. + */ void gtk_fixed_move (GtkFixed *fixed, GtkWidget *widget, -- 2.30.2